Web Service Task

About the Web Service Task

The Web Service task is useful if you are experienced with API and would like to trigger different workflows within the Qualtrics software, or to an external web service, when the respondent finishes the survey. For example, if your survey collects the respondent’s contact information, then a web service task can use the create contact API call to add the respondent to a contact list.

We also recommend visiting these web service-related pages for more assistance and background:

• Qualtrics Developer Hub
• Web Service Methods
• API Documentation
• Passing Information via Query Strings
• Piped Text

Setting Up a Web Service Task

Depending on how you prefer to format your body parameters, the setup will slightly differ. If you are using JSON or XML format, enter your body in the Body section. If you’d prefer URL-Encoded, you can add parameters as a query string to the URL field.

1. Create a workflow (or select an existing one) in your project or in the stand-alone Workflows page.
   
2. Make sure you’re in the Your workflows section.
3. Click Create a workflow.
4. Determine the schedule or the event that triggers your task. (See a comparison.)
5. Click Add task and select WebService.
   
6. Choose your authentication method. Your options include:
   
   • Authenticated: Perform an authenticated web service request. Your authentication options include basic (with a password and username), API key, and OAuth.
   • Non-authenticated: Perform a web service request without authentication.
7. Click Next.
8. If you selected an authenticated request, select your authorization credentials from the list, or click Add User Account to add new credentials. See Adding Authorization Credentials for more information.
   
   Qtip: You’ll be able to select any credentials you’ve previously added, or credentials added by a Brand Administrator in the Extensions tab.
9. Click Next.
10. If you’ve got a curl-formatted request, you can import it to automatically set your web service up. See the Using Curl Commands section for details.
    
11. If desired, add a Task summary at the top of your task. This is a description explaining the goal of the task.
12. Choose your web service’s Request method. See Web Service Methods for more information about each method.
    
    Qtip: If you’re using the Qualtrics API, the documentation will tell you what type of request to use.
    Attention: WebService tasks do not allow any URL redirects for non-GET requests. Only one redirect is allowed for GET requests.
13. Enter the URL for your request.
    Qtip: You can limit the domains that the web service task can connect to by specifying the domains in your extension domain settings.
14. If desired, click Add header to add a header. Specify the Key and Value. To remove a header, click the trash can icon next to the header.
    Qtip: Use the piped text icon, {a}, to insert piped text to pull in values from survey responses or previous tasks in the workflow.
    Attention: If using the Qualtrics API, you must include your API token through the header. See Adding a Header for Qualtrics API Requests for more information.
15. If you chose post, put, or patch, you’ll need to choose the format of your body. Options include JSON, URL-Encoded, XML, and Plain Text.
    
    
16. Determine how you want to specify the body of your request. You can add the body as Key-value pairs or Free text.
17. If you selected Key-value pairs, add the Key and its associated Value. Click Add key-value pair to add additional parameters.
    Attention: For POST, PUT, and PATCH requests you must specify a data type for each key-value pair.
18. Select a Data type.
    • Boolean: Select this data type if your data has one of two possible values.
    • JSON: Select this data type if your data is in JSON format.
    • Number: Select this data type if your data is numeric.
    • String: Select this data type if your data is in text format.
    • System Default: Select this data type if you want to use the native data type for your data. If a data type cannot be found this will default to the String type.
      Qtip: We recommend selecting one of the other data types to ensure your data is cast correctly.
      Attention: Key-value pairs that were configured before September 16, 2022 will have a data type of System Default.
    Qtip: The Data type field is only available when you select JSON and Key-value pairs in steps 13-14.
19. Select what happens if the data type cannot be cast.
    • Do not cast a data type, and flag as an error: If the data type cannot be cast, no data type will be cast and the task will fail. This can be seen in the Run History tab.
    • Cast the data type to system default: If the data type cannot be cast, the data type will be set to System Default.
20. If you selected Free Text, enter your body parameters in your selected format.
    
    Attention: You should not leave this field empty or have keys without values. Instead, either don’t include the field at all, or enter the term “null” to indicate empty values. We recommend excluding the field.
    Attention: Web service tasks do not currently support comments.
21. To test your web service, click Run test.
    
    Qtip: After clicking Run test, the result of your request will appear, letting you know if it was successful or not, and the resulting JSON or XML, if it was successful.
22. Click Add custom path to add JSON or XML paths. These paths let you use the results of your web service in piped text, to be used with other tasks in your workflow, such as a code task. If you tested your web service, you may automatically have values here, as Qualtrics will automatically pull them out of the results.
    Qtip: Click Add custom path to add additional paths, or click the trash can next to a path to delete it.
23. When finished setting up your workflow, click Save.

Adding Authorization Credentials

This section covers how to add authorization credentials for the web service task. You can add credentials using the Basic, API Key, or OAuth 2.0 method. To add credentials, click Add user account from the credential selection window.

Basic

Basic authentication requires you login with your account’s username and password.

1. Give your credentials a Name. This is for your organizational purposes only.
2. Choose Basic as the connection type.
3. Enter the Username required for authentication.
4. Enter the Password for authentication.
5. Click Connect account.

API Key

API Key authentication allows you to authenticate using a static API token.

1. Give your account a Name. This is for your organizational purposes only.
2. Choose API key as the connection type.
3. Enter the API Token used for authentication.
4. Click Connect account.

OAuth 2.0

OAuth2.0 authorization removes the need to use static API tokens or basic username and password to integrate with 3rd-party platforms. The web service task supports two different OAuth2.0 authorization types: authorization code and client credentials.

You can use OAuth 2.0 authorization to integrate seamlessly with many 3rd-party platforms. The Qualtrics web service implementation follows the official OAuth specification. However, some external systems may have slightly different configurations leading to incompatibilities with OAuth2.0 authorization in the web service task.

The following integrations are some examples that have been fully verified to work with OAuth2.0:

• Salesforce using the authorization code method.
• Jira using the authorization code method.
• Zoom using the authorization code method.

To authenticate using OAuth 2.0:

1. Give your account a Name. This is for your own organizational purposes only.
2. Choose OAuth as the connection type.
3. Choose your Grant type, or how the access token is retrieved. You may choose:
   • Authorization code
   • Client credentials
4. Enter the Client ID and Client secret.
5. Enter the Token endpoint.
6. If you selected authorization code as the grant type, enter the Authorization endpoint.
7. Click Connect account.

Renaming & Removing Credentials

To edit your credential’s name, click the three dots next to the account. To remove credentials, click Remove account.

Adding a Header for Qualtrics API Requests

When using the Qualtrics API, you must include your API token as a header in your web service.

1. Set up your web service task, select your credentials, and choose your request.
   
2. In the Headers section, enter X-API-TOKEN as the Key.
3. For the value, click the piped text icon, {a}.
4. Select your credentials from the list.
   

Mutual TLS

Mutual transport layer security (mTLS) is an additional, optional layer of security on top of standard API authentication mechanisms (such as API Token or OAuth). Mutual TLS ensures both the person connecting to an API / web service and the API / web service itself have secure, encrypted traffic in both directions. Once mTLS is enabled, all requests must present the correct client certificate for requests to succeed. If a caller makes a request using an invalid or missing client certificate, the API they are trying to call will block the request.

Requirements

Every service varies in whether it supports mTLS and what format(s) it provides key information in. We are only guaranteed to support mTLS for services whose match our requirements:

• Provide a private key
• Private key can be formatted into PKCS8
• Provide a certificate
• Certificate can be formatted into X.509

The Qualtrics public APIs support mTLS as described above.

mTLS is only supported for Authenticated web services created in workflows. All three authentication methods are supported (Basic, API key, and OAuth2.0).

Adding mTLS

1. Create your web service task.
   
2. Choose Authenticated.
   
3. Click Next.
4. Add a user account.
   
   Qtip: A Brand Administrator can connect to an account using the Extensions page.
   
5. Select a connection type and fill out your credentials.
   
6. Select Enable mTLS.
7. The Private key can be thought of as the unique identifier of the client trying to connect. This value needs to be in PKCS8 format.
   Qtip: If your key is in a different format, you can change use another program to change this format.
   Qtip: If you’re planning to use the Qualtrics API with your web service, see our API Documentation on mTLS. This documentation will show you how to pull the private key. When you paste the value in Qualtrics, you will need to include dashes that say “begin private key” and “end private key.”
8. The Public key is the mTLS certificate. This value needs to be in X.509 format.
   Qtip: If you’re planning to use the Qualtrics API with your web service, see our API Documentation on mTLS. This documentation will show you how to pull the certificate. When you paste the value in Qualtrics, you will need to include dashes that say “begin certificate” and “end certificate.”
9. When you’re finished, click Connect Account.
10. Proceed with your web service’s setup.

Using Curl Commands

Curl commands are one of many ways you can make HTTP requests, and are a valuable tool in passing information back and forth through URLs. You can import a curl command while you’re setting up your task to auto-populate different web service configurations.

Many API docs often provide curl examples you can use. Being able to copy and import these commands can thus make web service setup much quicker and easier.

For some examples of curl requests, look at the right on each of these API docs:

• Get Mailing List
• Create Reminder Distribution
• Update Contact Transaction
• List Users in Group

For a GET request, the curl command can be as simple as curl https://api.example.com/parameters. For curl commands that aren’t as simple as this, we’ll provide some common parameters.

Supported Curl Command Parameters

Here are some of the curl parameters the Qualtrics web service task supports:

Common Header Parameters

Above, we mentioned you can use curl commands to define headers. Headers serve various purposes in HTTP communication, such as providing information about the request and controlling authentication. The specific headers you use depend on the requirements of the application or API you’re using.

Here are some examples of header parameters:

Unsupported Parameters

Any curl parameters not listed above are not supported. Here are a few examples of curl command formats Qualtrics web service tasks do not support:

• --cookie to send cookies with the request.
• --L or --location for following redirects.
• --max-time for setting maximum request time.
• --o or --output for saving response to a file.
• --insecure to allow insecure connections.
• --A or --user-agent to specify user agent.

Importing Curl Commands

1. During your web service task setup, click Import cURL.
   
2. Paste your curl command in the box.
   
   Attention: Make sure you include your HTTP method in your curl request, especially if you’re copying a curl command from another platform.
   Qtip: Keep an eye out for parts of the request you need to fill out with your own information. For example, in the screenshot above, you’d replace “API Key” with your API token.

   Qtip: You can add a command in one single string, or you can mark line breaks using the escape character ( \ ). We do not support other line escapes (for example, ^ ). Here’s an example of a curl command with supported escape characters:

   curl https://www.google.com/accounts/test \
   -d accountType=GOOGLE \
   -d source=Google-cURL-Example \
   -d service=lh2

3. Click Import.
4. Web service fields will be filled automatically.

FAQs